VhsClient Methods

The VhsClient object contains the following methods:

AddHistoryPoint
AddHistoryPointEx
Connect
ContinueHistoryRead
ContinueHistoryReadEx
DeleteHistoryPoint
DeleteHistoryValueEx
Disconnect

GetConsoleData
GetMissingDataTimesForPoints
GetNamedArrayValues
GetNamedArrayValuesEx
GetPointStats
GetPointStatsEx
GetReferences
ListHistoryPointsEx

ListHistoryValuesEx
StartHistoryRead
StartHistoryReadEx
StoreHistoryList
StorePointHistory
StorePointHistoryEx
UpdateHistoryValueEx

Methods ending in Ex represent extended messaging functionality, for example, getting and storing the Long Point Id in the entry record, and getting and storing extended value fields, e.g., Rollup, Status, TimeStamp, UserStats, and Value fields.

A description for each variant object can be found in VhsClient Helper Objects.

AddHistoryPoint

The AddHistoryPoint method adds a new history point to a VHS.

Syntax

AddHistoryPoint(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	AddHistoryPointReq
Response	Yes	The response object that contains the output of this method.	AddHistoryPointResp

Remarks

Returns 0 if successful and a non-zero value if an error occurred. Adding a tag that has already been added will not generate an error. Adding a new point to the VHS in this way does not result in the corresponding CVS actually recording new values to the VHS for the point. History must be enabled in the PNT for the CVS to process new values and log them to the VHS. This method is not generally used.

Example

The following example adds a new point to CYGDEMO.UIS and alerts the user of any errors.

Copy

AddHistoryPoint

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Sub VhsAddHistoryPoint()
    Dim VhsClient,req, resp, tag
        Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
        Set req = CreateObject("CxVhsLib.AddHistoryPointReq")
        Set resp = CreateObject("CxVhsLib.AddHistoryPointResp")
        Set tag = CreateObject("CxVhsLib.HistoryTagString")
        VhsClient.Connect("CYGDEMO.VHS")
     
        'The point to be created
        tag.TagString = "CYGDEMO.UIS.00001235"
        req.TagString = tag 
     
        VhsClient.AddHistoryPoint req, resp
     
        If resp.Error <> 0 Then
            edtMessageBox.Text = "Error number " & resp.Error
        Else
            edtMessageBox.Text = "Completed successfully"
        End If
End Sub

AddHistoryPointEx

The AddHistoryPoint method adds a new history point to a VHS.

Syntax

AddHistoryPointEx(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	AddHistoryPointExReq
Response	Yes	The response object that contains the output of this method.	AddHistoryPointExResp

Remarks

Example

The following example adds a new point to CYGDEMO.UIS and alerts the user of any errors.

Copy

AddHistoryPointEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Sub VhsAddHistoryPointEx()
    Dim VhsClient,req, resp, tag
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.AddHistoryPointExReq")
    Set resp = CreateObject("CxVhsLib.AddHistoryPointExResp")
    Set tag = CreateObject("CxVhsLib.HistoryTagStringEx")
    VhsClient.Connect("CYGDEMO.VHS")
     
    'The point to be created
    tag.TagString = "CYGDEMO.UIS.00001235:MY_LONG_ID"
    req.TagStringEx = tag
    req.ExpirationDays = 9999
    req.UserId = vhsClient.UserId
    
    VhsClient.AddHistoryPointEx req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        edtMessageBox.Text = "Completed successfully"
    End If
End Sub

Connect

The Connect method connects the object to a service.

Syntax

Connect(DomainSiteService As String)

Parameters

Parameter	Required	Description
DomainSiteService	Yes	The [Domain]Site.Service to which to connect. The domain is optional. The service must be a valid one.

Remarks

Returns 0 if successful and a non-zero value if the connection failed.

Example

The following example connects the Client object to the CYGDEMO.<SVC> on domain 5410:

Copy

Connect

1
2
3
4
5
6
7
8
Sub VhsConnect()

    'Connect to a VHS
    Dim VhsClient
    Set VhsClient = CreateObject("CxVhsLib.VhsClient")
    VhsClient.Connect("[5410]CYGDEMO.VHS")

End Sub

ContinueHistoryRead

The ContinueHistoryRead method is used after StartHistoryRead for successive calls until all history entries have been returned.

Syntax

ContinueHistoryRead(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	ContinueHistoryReadReq
Response	Yes	The response object that contains the output of this method.	HistoryReadResp

Remarks

When the Response object’s Error variable is equal to 10, the end of the history values has been reached.

Example

The following example reads two more values from the history. It uses a global variable, g_Restart, that was set in a StartHistoryRead method.

Copy

ContinueHistoryRead

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Sub VhsContinueHistoryRead()
    Dim VhsClient, req, resp
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.ContinueHistoryReadReq")
    Set resp = CreateObject("CxVhsLib.HistoryReadResp")
    VhsClient.Connect("CYGDEMO.VHS")
     
    req.Count = 2
    req.Restart = g_Restart  
     
    VhsClient.ContinueHistoryRead req, resp
     
    g_Restart = resp.Restart
     
    If resp.Error = 10 Then
        edtMessageBox.Text = "End of history has been reached"
    Elseif resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        edtMessageBox.Text = "Completed successfully"
        For i = 0 To resp.Count - 1
            ListBox2.AddString(i & " - " & _
            resp.entry(i).Status & " - " & _
            resp.entry(i).TimeStamp & " - " & _
            resp.entry(i).Value)
        Next  
    End If
End Sub

ContinueHistoryReadEx

The ContinueHistoryReadEx method is used after StartHistoryReadEx for successive calls until all history entries have been returned.

Syntax

ContinueHistoryReadEx(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	ContinueHistoryReadExReq
Response	Yes	The response object that contains the output of this method.	HistoryReadExResp

Remarks

When the Response object’s Error variable is equal to 10, the end of the history values has been reached.

Example

The following example reads two more values from the history. It uses a global variable, g_Restart, that was set in a StartHistoryReadEx method.

Copy

ContinueHistoryReadEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
Sub VhsContinueHistoryReadEx()
    Dim VhsClient, req, resp
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.ContinueHistoryReadExReq")
    Set resp = CreateObject("CxVhsLib.HistoryReadExResp")
    VhsClient.Connect("CYGDEMO.VHS")
     
    req.Count = 3
    req.Restart = g_Restart  
     
    VhsClient.ContinueHistoryReadEx req, resp
     
    g_Restart = resp.Restart
     
    If resp.Error = 10 Then
        edtMessageBox.Text = "End of history"
    Elseif resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        edtMessageBox.Text = "Completed successfully"
        For i = 0 To resp.Count - 1
            ListBox2.AddString(i & " - " & _
            resp.entry(i).Status & " - " & _
            resp.entry(i).UserStatus & " - " & _
            resp.entry(i).TimeStamp & " - " & _
            resp.entry(i).Value)
        Next
    End If
End Sub

DeleteHistoryPoint

The DeleteHistoryPoint method deletes a point from the VHS.

Syntax

DeleteHistoryPoint(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	DeleteHistoryPointReq
Response	Yes	The response object that contains the output of this method.	DeleteHistoryPointResp

Remarks

Returns 0 if successful and a non-zero value if an error occurred.

Example

The following example deletes CYGDEMO.UIS.00001235 from the VHS.

Copy

DeleteHistoryPoint

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Sub VhsDeleteHistoryPoint()
    Dim VhsClient, req, resp, tag
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.DeleteHistoryPointReq")
    Set resp = CreateObject("CxVhsLib.DeleteHistoryPointResp")
    Set tag = CreateObject("CxVhsLib.HistoryTagString")
    VhsClient.Connect("CYGDEMO.VHS")
     
    'The point to be deleted
    tag.TagString = "CYGDEMO.UIS.00001235"
    req.TagString = tag
     
    VhsClient.DeleteHistoryPoint req, resp
     
    'Error handling
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        edtMessageBox.Text = "Completed successfully"
    End If
End Sub

DeleteHistoryValueEx

The DeleteHistoryValueEx method deletes a history value from a point in the VHS.

Syntax

DeleteHistoryValueEx(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	DeleteHistoryValueExReq
Response	Yes	The response object that contains the output of this method.	DeleteHistoryValueExResp

Remarks

Returns 0 if successful and a non-zero value if an error occurred.

Example

The following example deletes a history value obtained from ListHistoryValuesEx (g_ValueEntryEx). It is also possible to manually input the history value.

Copy

DeleteHistoryValueEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Sub VhsDeleteHistoryValueEx()
    Dim VhsClient, req, resp, tag
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.DeleteHistoryValueExReq")
    Set resp = CreateObject("CxVhsLib.DeleteHistoryValueExResp")
    Set tag = CreateObject("CxVhsLib.HistoryTagStringEx")
    VhsClient.Connect("CYGDEMO.VHS")
     
    tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF"
    req.TagStringEx = tag
    req.ValueEntryEx = g_ValueEntryEx
    req.Operations = 1
     
    VhsClient.DeleteHistoryValueEx req, resp
     
    'Error handling
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        edtMessageBox.Text = "Completed successfully"
    End If
End Sub

Disconnect

The Disconnect method disconnects from the connected service.

Syntax

Disconnect() As Integer

Remarks

The Disconnect method returns 0 if successful and a non-zero value if the disconnect failed.

Example

The following example disconnects the Client object from the connected service, and pops a message box if it is unsuccessful:

Copy

Disconnect

1
2
3
4
5
6
7
8
9
10
11
Sub Svc.Disconnect()
 
    <SvcClient>.Disconnect()
    MsgBox "Service has disconnected."
    
    If <SvcClient>.Disconnect <> 0 
    Then
        MsgBox "Failed to disconnect."
    End If

End Sub

GetConsoleData

The GetConsoleData method returns the console text and display attributes as two 25x80 arrays of unsigned characters.

Syntax

GetConsoleData(ByRef pText, ByRef pAttr) As Integer

Parameters

Parameter	Required	Description
pText	Yes	A two-dimensional 25x80 array of console text attributes returned by this method.
pAttr	Yes	A two-dimensional 25x80 array of console display attributes returned by this method.

Remarks

This method returns 0 if successful.

Example

The following example writes the console text and display attributes to a CSV file.

Copy

GetConsoleData

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
Sub
    Dim aryText, aryAttr, nRet
    nRet = <NameofServiceClientObject>.GetConsoleData(aryText, aryAttr)
 
    ' Write text attributes to CSV file
    Dim i, j, strMsg
        For i = 0 To UBound(aryText, 1)
        For j = 0 To UBound(aryText, 2)
            strMsg = strMsg + CStr(aryText(i, j)) + ","
        Next
            strMsg = strMsg + vbCr
    Next
 
    dim fso, file
    Set fso = CreateObject("Scripting.FileSystemObject")
    Set file = fso.OpenTextFile("c:\console_text_attrs.csv", 2, True)
    file.WriteLine(strMsg)
    file.Close 
 
    strMsg = ""
 
    ' Write display attributes to CSV file
        For i = 0 To UBound(aryAttr, 1)
        For j = 0 To UBound(aryAttr, 2)
            strMsg = strMsg + CStr(aryAttr(i, j)) + ","
        Next
            strMsg = strMsg + vbCr
    Next
 
    Set file = fso.OpenTextFile("c:\console_disp_attrs.csv", 2, True)
    file.WriteLine(strMsg)
    file.Close 
 
    MsgBox nRet
End Sub

GetMissingDataTimesForPoints

The GetMissingDataTimesForPoints method gets dates in an interval that don’t have the specified number of value updates.

Syntax

GetMissingDataTimesForPoints(Points As Variant, Period As Integer, Units As String, MinRequired As Integer, StartTime As Variant, EndTime As String, MissingDataTimes As String, ErrorTextOut as String) As Boolean

Parameters

Parameter	Required	Description
Points	Yes	Array of points to check for missing data.
Period	Yes	The interval in which you expect values to exist.
Units	Yes	The interval of the unit. This can be "Seconds," "Minute," "Hours," or "Days."
MinRequired	Yes	Minimum number of values expected to be within the interval. If there is less than this number, the interval will be returned in MissingDataTimes.
StartTime	Yes	The interval time you want to start searching for missing values.
EndTime	Yes	The interval time you want to stop searching for values.
MissingDataTimes	Yes	Output, two-dimensional array. The first column of the array is the point tag. The second column is an array where index 0 is the name of the point, and index 1 is an array of timestamps that represent intervals that don’t meet the minimum number of required values.
ErrorTextOut	Yes	Output. An error message, if applicable.

Example

The following example gets all the days in February 2023 that CYGDEMO.UIS.00000068 and CYGDEMO.UIS.00000069 were not updated at least once.

Copy

GetMissingDataTimesForPoints

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Sub VhsGetMissingDataTimesForPoints
    Dim objVhs, tags, arrPoints, arrTimes, strError, i
    Set objVhs = CreateObject("CxVhsLib.VhsClient.1")
    objVhs.Connect("CYGDEMO.VHS")
     
    tags = Array("CYGDEMO.UIS.00000068", "CYGDEMO.UIS.00000069")
     
    'Get all days from February 1, 2023 until the current date
    'That haven't been updated at least once
    objVhs.GetMissingDataTimesForPoints tags, 1, "Days", 1, _
    CDate("02/01/2023"), Now, arrPoints, strError
     
    If strError <> "" Then
    MsgBox strError
    Else
        'Set arrTimes to all the timestamps for the first point
        arrTimes = arrPoints(0,1)
        'Prints the point name and all its timestamps
        For i = 0 To UBound(arrTimes)
            listbox2.AddString(arrPoints(0,0) & " - " & CDate(arrTimes(i)))
        Next
         
        'Set arrTimes to all the timestamps for the second point
        arrTimes = arrPoints(1,1)
        'Prints the point name and all its timestamps
        For i = 0 To UBound(arrTimes)
            listbox2.AddString(arrPoints(1,0) & " - " & CDate(arrTimes(i)))
        Next
    End If
End Sub

GetNamedArrayValues

The GetNamedArrayValues method reads the history entries from multiple points that were in effect for the given date.

Syntax

GetNamedArrayValues(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	GetNamedArrayValuesReq
Response	Yes	The response object that contains the output of this method.	GetNamedArrayValuesResp

Remarks

If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.

Example

The following example displays the history entry data for two points in a list box.

Copy

GetNamedArrayValues

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Sub VhsGetNamedArrayValues()
    Dim VhsClient, req, resp, tag0, tag1
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.GetNamedArrayValuesReq")
    Set resp = CreateObject("CxVhsLib.GetNamedArrayValuesResp")
    Set tag0 = CreateObject("CxVhsLib.HistoryTagString")
    Set tag1 = CreateObject("CxVhsLib.HistoryTagString")
    VhsClient.Connect("CYGDEMO.VHS")
     
    req.count = 2
    tag0.TagString = "CYGDEMO.UIS.00000068"
    req.TagString(0) = tag0
    req.TimeStamp(0) = CDate("1/1/2023 15:48:00")
     
    tag1.TagString = "CYGDEMO.UIS.00000069"
    req.TagString(1) = tag1
    req.TimeStamp(1) = CDate("1/1/2023 15:48:00")
     
    VhsClient.GetNamedArrayValues req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        ListBox2.ResetContent
        Dim i
        For i = 0 To resp.count - 1
            ListBox2.AddString("Status - " & resp.entry(i).Status & "; TimeStamp - " & resp.entry(i).Timestamp & "; Value " & resp.entry(i).Value)
        Next
    End If
End Sub

GetNamedArrayValuesEx

The GetNamedArrayValuesEx method reads the history entries from multiple history points that were in effect for the given date.

Syntax

GetNamedArrayValuesEx(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	GetNamedArrayValuesExReq
Response	Yes	The response object that contains the output of this method.	GetNamedArrayValuesExResp

Remarks

If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.

Example

The following example displays the history entry data for two points in a list box.

Copy

GetNamedArrayValuesEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Sub VhsGetNamedArrayValuesEx()
    Dim VhsClient, req, resp, tag0, tag1
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.GetNamedArrayValuesExReq")
    Set resp = CreateObject("CxVhsLib.GetNamedArrayValuesExResp")
    Set tag0 = CreateObject("CxVhsLib.HistoryTagStringEx")
    Set tag1 = CreateObject("CxVhsLib.HistoryTagStringEx")
    VhsClient.Connect("CYGDEMO.VHS")
     
    req.count = 2
    tag0.TagString = "CYGDEMO.UIS.00000068"
    req.TagString(0) = tag0
    req.TimeStamp(0) = CDate("1/1/2023 15:48:00")
     
    tag1.TagString = "CYGDEMO.UIS.00000069"
    req.TagString(1) = tag1
    req.TimeStamp(1) = CDate("1/1/2023 15:48:00")
     
    VhsClient.GetNamedArrayValuesEx req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        edtMessageBox.text = resp.count
        ListBox2.ResetContent
        Dim i
        For i = 0 To resp.Count - 1
            ListBox2.AddString("Status - " & resp.entry(i).Status & ; Userstatus - " & resp.entry(i).UserStatus & "; TimeStamp - " & resp.entry(i).Timestamp & "; Value - " & resp.entry(i).Value)
        Next
    End If
End Sub

GetPointStats

The GetPointStats method gets statistics for a given history point.

Syntax

GetPointStats(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	GetPointStatsReq
Response	Yes	The response object that contains the output of this method.	GetPointStatsResp

Remarks

Returns 0 if successful and a non-zero value if an error occurred.

Example

The following example gets statistics for CYGDEMO.UIS.00000068 and displays them in a list box.

Copy

GetPointStats

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Sub VhsGetPointStats()
    Dim VhsClient, req, resp, tag
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.GetPointStatsreq")
    Set resp = CreateObject("CxVhsLib.GetPointStatsresp")
    Set tag = CreateObject("CxVhsLib.HistoryTagString")
    bjVhs.Connect("CYGDEMO.VHS")
     
    tag.TagString = "CYGDEMO.UIS.00000068"
    req.TagString = tag
     
    VhsClient.GetPointStats req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        ListBox2.ResetContent
        ListBox2.AddString("Expiration Date: " & resp.ExpirationDays)
        ListBox2.AddString("First History Entry: " & resp.TimeStampStart)
        ListBox2.AddString("Last History Entry: " & resp.TimeStampEnd)
        ListBox2.AddString("Total History Entries: " & resp.Entrycount)
    End If
End Sub

GetPointStatsEx

The GetPointStatsEx method gets statistics for an array of history points.

Syntax

GetPointStatsEx(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	GetPointStatsExReq
Response	Yes	The response object that contains the output of this method.	GetPointStatsExResp

Remarks

Returns 0 if successful and a non-zero value if an error occurred.

Example

The following example gets statistics for CYGDEMO.UIS.00000068 and CYGDEMO.UIS.00000069 and displays them in a list box.

Copy

GetPointStatsEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
Sub VhsGetPointStatsEx()
    Dim VhsClient, req, resp, bRc, tag1, tag2
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.GetPointStatsExReq")
    Set resp = CreateObject("CxVhsLib.GetPointStatsExResp")
    Set tag0 = CreateObject("CxVhsLib.HistoryTagStringEx")
    Set tag1 = CreateObject("CxVhsLib.HistoryTagStringEx")
    bRc = VhsClient.Connect("CYGDEMO.VHS")
     
    req.Count = 2
    tag0.TagString = "CYGDEMO.UIS.00000069:CYG_METER_PSTATIC"
    tag1.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF"
    req.TagString(0) = tag0
    req.TagString(1) = tag1
     
    VhsClient.GetPointStatsEx req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        ListBox2.ResetContent
        Dim i
        For i = 0 To resp.Count - 1
            ListBox2.AddString("Point Number: " & i)
            ListBox2.AddString("Point Error: " & resp.PointError(i))
            ListBox2.AddString("Total History Entries: " & resp.Statistics(i).EntryCount)
            ListBox2.AddString("First History Entry: " & resp.Statistics(i).TimeStampStart)
            ListBox2.AddString("Last History Entry: " & resp.Statistics(i).TimeStampEnd)
            ListBox2.AddString("Expiration Date: " & resp.Statistics(i).ExpirationDays)
            ListBox2.AddString("")
        Next
    End If
End Sub

GetReferences

The GetReferences method refreshes the list of services referenced by the connected service.

Syntax

GetReferences() As Integer

Return Values

This method returns all references for the connected service.

Example

The following example refreshes the connected services:

Copy

GetReferences

1
2
3
4
5
6
Sub GetReferences()
 
    <NameofServiceClientObject>.GetReferences
    MsgBox "Services references retrieved"

End Sub

The following example refreshes the referenced services.

Copy

GetReferences

1
2
3
4
5
6
7
8
9
Sub VhsGetReferences()

    Dim VhsClient
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    VhsClient.Connect("CYGDEMO.VHS")
     
    VhsClient.GetReferences()
    
End Sub

ListHistoryPointsEx

The ListHistoryPointsEx method lists history points in alphabetic order from the given start index. The ListHistoryPointsEx method has a upper bound array count of 53; the method can only retrieve a maximum of 53 response items per request. The only way to get all points is to iterate through using the last returned item as the new starting point. See the second example below.

Syntax

ListHistoryPointsEx(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	ListHistoryPointsExReq
Response	Yes	The response object that contains the output of this method.	ListHistoryPointsExResp

Remarks

Returns 0 if successful and a non-zero value if an error occurred.

Examples

The following example gets a list of all history points whose Point ID is greater than 00000123.

Copy

ListHistoryPointsEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Sub VhsListHistoryPointsEx()
    Dim VhsClient, req, resp
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.ListHistoryPointsExReq")
    Set resp = CreateObject("CxVhsLib.ListHistoryPointsExResp")
    Set tag = CreateObject("CxVhsLib.HistoryTagStringEx")
    VhsClient.Connect("CYGDEMO.VHS") 

    tag.TagString = "CYGDEMO.UIS.00000123:FREEZIE_METER_VET"
    req.TagString = tag
    VhsClient.ListHistoryPointsEx req, resp 

    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        ListBox2.ResetContent
        Dim i
        For i = 0 To resp.Count - 1
            ListBox2.AddString( i & " - " & resp.Statistics(i).ExpirationDays & " - " & resp.Statistics(i).TimeStampStart & " - " & resp.Statistics(i).TimeStampEnd & " - " & resp.Statistics(i).Entrycount & " - " & resp.TagString(i).TagString)
        Next
    End If
End Sub

The following example iterates through the returned values for ListHistoryPointsEx:

Copy

ListHistoryPointsEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
' VHS Client Request and Response objects.
 
Dim objVHSClient : Set objVHSClient = CreateObject("CxVHS.VhsClient")
Dim objVHSRequest : Set objVHSRequest = CreateObject("CxVhsLib.ListHistoryPointsExReq")
Dim objVHSResponse : Set objVHSResponse = CreateObject("CxVhsLib.ListHistoryPointsExResp")
Dim objVHSTag : Set objVHSTag = CreateObject("CxVhsLib.HistoryTagStringEx")
 
' Connect the Client to the Service.
Call objVHSClient.Connect("CYGDEMO.VHS")
 
' Prepare the Request
objVHSTag.TagString = "CYGDEMO.UIS.00000000" ' Let's start at "Zero" to try and get everything.
objVHSRequest.TagString = objVHSTag
 
' Send the Initial Request
Call objVHSClient.ListHistoryPointsEx(objVHSRequest, objVHSResponse)
Dim blnFlag : blnFlag = True
 
' Iterate through the response object
Dim intX : intX = 0
Dim intY : intY = 0 ' The UB of the return array
ReDim aryVHSPoints(intX)
 
Dim objFSO : Set objFSO = CreateObject("Scripting.FileSystemObject")
Dim objFile : Set objFile = objFSO.CreateTextFile("C:\temp\ListHistoryPointsEx.txt", True, -2)
 
Dim strHeader : strHeader = "******************** ListHistoryValuesEx Results ********************"
Dim strFooter : strFooter = "*********************************************************************"
 
Dim objPoints : Set objPoints = CreateObject("CxScript.Points")
Dim objPoint
 
Call objFile.Write(strHeader & vbCrLf & vbCrLf)
 
Dim blnStop : blnStop = True
 
Do While(intY <= objVHSResponse.TotalPointCount)
 
    For intX = 0 To (objVHSResponse.Count -1)
        ReDim Preserve aryVHSPoints(intY)
        aryVHSPoints(intY) = objVHSResponse.TagString(intX).TagString
        intY = intY + 1
        
    Next
     
    ' Continue the loop till the end...
    On Error Resume next
    Set objPoint = objPoints.Point(aryVHSPoints(intY -1))
    objVHSTag.TagString = objPoint.Tag
    objVHSRequest.TagString = objVHSTag
    Call objVHSClient.ListHistoryPointsEx(objVHSRequest, objVHSResponse)
 
Loop
 
ReDim Preserve aryVHSPoints(intY -1)
intY = 0
 
For Each thing In aryVHSPoints
    Call objFile.Write(intY+1 & " | " & thing & vbCrLf)
    intY = intY + 1
 
Next
 
Call objFile.Write(strFooter)

ListHistoryValuesEx

The ListHistoryValuesEx method reads the history values from a point in chronological order based on the given timestamp. The ListHistoryValuesEx has a upper bound array count of 111; the method can only retrieve a maximum of 111 response items per request. The only way to get all values is to iterate through using the last returned item as the new starting point. See the second example below.

Syntax

ListHistoryValuesEx(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	ListHistoryValuesExReq
Response	Yes	The response object that contains the output of this method.	ListHistoryValuesExResp

Remarks

Returns 0 if successful, or return codes: NO_HISTORY_FOR_TIME (12) indicating that there is no history for the time requested or END_OF_HISTORY (10) indicating that there is no more history to retrieve.

We recommend avoiding these message wrappers in favor of the more user-friendly iterators: PointIterator, ValueIterator, and ValueIteratorReverse.

Examples

The following example gets all the history values for a point after January 1, 2023 and displays them in a list box. It also stores the first history value in a global variable so it can be used by other methods.

Copy

ListHistoryValuesEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Sub VhsListHistoryValuesEx()
    Dim VhsClient, req, resp, tag
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.ListHistoryValuesExReq")
    Set resp = CreateObject("CxVhsLib.ListHistoryValuesExResp")
    Set tag = CreateObject("CxVhsLib.HistoryTagStringEx")
    VhsClient.Connect("CYGDEMO.VHS")
     
    tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF"
    Req.TagString = tag
    Req.TimeStampStart = CDate("1/1/2023")
     
    VhsClient.ListHistoryValuesEx req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        Dim i
        ListBox2.ResetContent
        For i = 0 To resp.Count - 1
            ListBox2.AddString(resp.valueEntry(i).Status & " - " & resp.valueEntry(i).UserStatus & " - " & resp.valueEntry(i).TimeStamp & " - " & resp.valueEntry(i).Value)
        Next
         
        'Sets a global variable to the first value entry
        'so it can be used by other methods
        Set g_ValueEntryEx = resp.valueEntry(0) 
    End If
End Sub

The following example iterates through the returned values for ListHistoryValuesEx:

Copy

ListHistoryValuesEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
Sub VhsListHistoryValuesEx(Byval Cur_Tag, Byval Vhs_Site)
 
    Dim request : Set request = CreateObject("CxVhsLib.ListHistoryValuesExReq")
    Dim response : Set response = CreateObject("CxVhsLib.ListHistoryValuesExResp")
    Dim strHistTag : Set strHistTag = CreateObject("CxVhsLib.HistoryTagStringEx")
     
    Dim strHistoryEntries : strHistoryEntries = ""
    Dim intUnreliable : intUnreliable = 0
     
    VhsClient.Connect(strVHSSite)
     
    strHistTag.TagString = strTag
    request.TagString = strHistTag
    request.TimeStampStart = CDate("1/1/1985")
     
    Dim loop_until
        loop_until = True
         
        Dim X : X = 0
         
        Dim Z : Z = 0
         
        While(loop_until)
         
        Z = 0
         
        VhsClient.ListHistoryValuesEx request, response
         
        Dim i : i = 0
        Dim j : j = 0
         
            Dim timeEntry
            Dim valueEntry
            Dim statusEntry
            Dim historyEntry
            Dim checkEntry
             
            Dim checker
            Dim Rchecker
            Dim results
             
            If(response.Error <> 0 And response.Error <> 10)Then
             
            ' if the response error is 0, there is no error
            ' if the response error is 10, this means "END_OF_HISTORY" -- we're done
             
            Else
     
                For i = 0 To response.Count - 1
                 
                ' What can you do with the results?
                 
                'objDictionary_Time.SetKeyValue X,response.ValueEntry(i).Value
                'objDictionary_Value.SetKeyValue X,response.ValueEntry(i).Timestamp
                'objDictionary_Status.SetKeyValue X,response.ValueEntry(i).Status
                 
                'timeEntry = objDictionary_Time.FindValue(X)
                'valueEntry = objDictionary_Value.FindValue(X)
                'statusEntry = objDictionary_Status.FindValue(X)
                 
                X = X + 1
                Z = Z + 1
     
            Next
     
        End If
     
            If(response.Count = 111)Then
     
            ' Let's start at the last timepoint retrieved and move forward.
            request.TimeStampStart = CDate(response.ValueEntry(Z-1).Timestamp)
     
        Else
            ' Exit
            loop_until = False
     
        End if
     
    Wend
 
End Sub

StartHistoryRead

The StartHistoryRead method reads the history entries within an inclusive GMT date range.

Syntax

StartHistoryRead(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	StartHistoryReadReq
Response	Yes	The response object that contains the output of this method.	HistoryReadResp

Remarks

Returns 0 if successful and a non-zero value if an error occurred. If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.

Example

The following example reads two history entries between January 1, 2023 and the current date. It then stores Restart in a global variable so that ContinueHistoryRead can read the next set of entries.

Copy

StartHistoryRead

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Sub VhsStartHistoryRead()
    Dim VhsClient, req, resp, tag
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.StartHistoryReadReq")
    Set resp = CreateObject("CxVhsLib.HistoryReadResp")
    Set tag = CreateObject("CxVhsLib.HistoryTagString")
    VhsClient.Connect("CYGDEMO.VHS")
     
    tag.TagString = "CYGDEMO.UIS.00000068"
    req.TagString = tag
    req.Count = 2
    req.TimeStampStart = CDate("01/01/2023")
     
    VhsClient.StartHistoryRead req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        g_restart = resp.Restart
         
        ListBox2.ResetContent
        For i = 0 To resp.Count - 1
            ListBox2.AddString(i & " - " & resp.entry(i).Status & " - " & resp.entry(i).TimeStamp & " - " & resp.entry(i).Value)
        Next  
    End If
End Sub

StartHistoryReadEx

The StartHistoryReadEx method reads the history entries within an inclusive GMT date range.

Syntax

StartHistoryReadEx(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	StartHistoryReadExReq
Response	Yes	The response object that contains the output of this method.	HistoryReadExResp

Remarks

This method is capable of returning rollups for the given period. By default, raw values are returned. Returns 0 if successful and a non-zero value if an error occurred. If no history entries exist at the exact start time, the first history entry prior to the start time will be returned.

Example

The following example reads the last value entry from each 30 day period. It then stores Restart in a global variable so that ContinueHistoryReadEx can read the next three entries.

Copy

StartHistoryReadEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Sub VhsStartHistoryReadEx()
    Dim VhsClient, req, resp, tag
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.StartHistoryReadExReq")
    Set resp = CreateObject("CxVhsLib.HistoryReadExResp")
    Set tag = CreateObject("CxVhsLib.HistoryTagStringEx")
    VhsClient.Connect("CYGDEMO.VHS")
     
    tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF"
    req.TagString = tag
    req.TimeStampStart = "12/3/2023"
    req.TimeStampEnd = Now
    req.RollupType = 9     'Gets the last value entry...
    req.RollupPeriod = 30  '...from each thirty...
    req.RollupUnits = 3    '...day period
    req.Count = 3
     
    VhsClient.StartHistoryReadEx req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        g_restart = resp.Restart
         
        ListBox2.ResetContent
        For i = 0 To resp.Count - 1
            ListBox2.AddString(resp.Entry(i).Status & " - " & resp.entry(i).UserStatus & " - " & resp.entry(i).TimeStamp & " - " & resp.entry(i).Value)
        Next
    End If
End Sub

StoreHistoryList

The StoreHistoryList method stores history entries for multiple history points. StoreHistoryList replaces EditHistoryPoints and InsertHistoryList, which are now obsolete.

Syntax

StoreHistoryList(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	StoreHistoryListReq
Response	Yes	The response object that contains the output of this method.	StoreHistoryListResp

Remarks

The entries do not have to be in chronological order because they will be correctly inserted or appended, however performance is better if they are. Returns 0 if successful and a non-zero value if an error occurred.

Example

The following example stores new value entries for two history points.

Copy

StoreHistoryList

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
Sub VhsStoreHistoryList()
    Dim VhsClient, req, resp, entry0, entry1, tag0, tag1
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.StoreHistoryListReq")
    Set resp = CreateObject("CxVhsLib.StoreHistoryListResp")
    Set entry0 = CreateObject("CxVhsLib.HistoryEntry")
    Set entry1 = CreateObject("CxVhsLib.HistoryEntry")
    Set tag0 = CreateObject("CxVhsLib.HistoryTagString")
    Set tag1 = CreateObject("CxVhsLib.HistoryTagString")
    VhsClient.Connect("CYGDEMO.VHS")
     
    Req.Count = 2
     
    tag0.TagString = "CYGDEMO.UIS.00000068"
    req.TagString(0) = tag0
    entry0.Status = 7
    entry0.TimeStamp = Now
    entry0.Value = 999
    req.Entry(0) = entry0
     
    tag1.TagString = "CYGDEMO.UIS.00000069"
    req.TagString(1) = tag1
    entry1.Status = 7
    entry1.TimeStamp = Now
    entry1.Value = 123
    Req.Entry(1) = entry1
     
    VhsClient.StoreHistoryList req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        edtMessageBox.Text = "Completed Successfully"
    End If
End Sub

StorePointHistory

The StorePointHistory method stores multiple history entries for a single point.

Syntax

StorePointHistory(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	StorePointHistoryReq
Response	Yes	The response object that contains the output of this method.	StorePointHistoryResp

Remarks

Example

The following example stores two history entries for a point. The first entry is inserted at the appropriate time, while the second entry is appended to the history list to be the latest value.

Copy

StorePointHistory

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
Sub VhsStoreHistoryList()
    Dim VhsClient, req, resp, entry0, entry1, tag0, tag1
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.StoreHistoryListReq")
    Set resp = CreateObject("CxVhsLib.StoreHistoryListResp")
    Set entry0 = CreateObject("CxVhsLib.HistoryEntry")
    Set entry1 = CreateObject("CxVhsLib.HistoryEntry")
    Set tag0 = CreateObject("CxVhsLib.HistoryTagString")
    Set tag1 = CreateObject("CxVhsLib.HistoryTagString")
    VhsClient.Connect("CYGDEMO.VHS")
     
    Req.Count = 2
     
    tag0.TagString = "CYGDEMO.UIS.00000068"
    req.TagString(0) = tag0
    entry0.Status = 7
    entry0.TimeStamp = Now
    entry0.Value = 999
    req.Entry(0) = entry0
     
    tag1.TagString = "CYGDEMO.UIS.00000069"
    req.TagString(1) = tag1
    entry1.Status = 7
    entry1.TimeStamp = Now
    entry1.Value = 123
    Req.Entry(1) = entry1
     
    VhsClient.StoreHistoryList req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        edtMessageBox.Text = "Completed Successfully"
    End If
End Sub

StorePointHistoryEx

The StorePointHistory method stores multiple history entries for a single point.

Syntax

StorePointHistory(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	StorePointHistoryExReq
Response	Yes	The response object that contains the output of this method.	StorePointHistoryExResp

Remarks

Example

The following example stores two history entries for a point. The first entry is inserted at the appropriate time, while the second entry is appended to the history list to be the latest value.

Copy

StorePointHistoryEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
Sub VhsStorePointHistoryEx()
    Dim VhsClient, req, resp, entry0, entry1, tag
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.StorePointHistoryExReq")
    Set resp = CreateObject("CxVhsLib.StorePointHistoryExResp")
    Set entry0 = CreateObject("CxVhsLib.HistoryEntryEx")
    Set entry1 = CreateObject("CxVhsLib.HistoryEntryEx")
    Set tag = CreateObject("CxVhsLib.HistoryTagStringEx")
    VhsClient.Connect("CYGDEMO.VHS")
     
    req.Count = 2
     
    tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF"
    req.TagString = tag
     
    entry0.Status = 7
    entry0.UserStatus = 0
    entry0.TimeStamp = CDate("01/02/2023")
    entry0.Value = 111
    req.Entry(0) = entry0
     
    entry1.Status = 7
    entry1.UserStatus = 0
    entry1.TimeStamp = Now
     entry1.Value = 222
    req.Entry(1) = entry1
     
    VhsClient.StorePointHistoryEx req, resp
     
    If resp.Error <> 0 Then
        edtMessageBox.Text = "Error number " & resp.Error
    Else
        edtMessageBox.Text = "Completed Successfully"
    End If
End Sub

UpdateHistoryValueEx

The UpdateHistoryValueEx method updates a point’s history value.

Syntax

UpdateHistoryValueEx(Request As Variant, Response As Variant) As Integer

Parameters

Parameter	Required	Description	Variant
Request	Yes	The request object that contains the parameters for this method.	UpdateHistoryValueExReq
Response	Yes	The response object that contains the output of this method.	UpdateHistoryValueExResp

Remarks

Returns 0 if successful and a non-zero value if an error occurred.

Example

The following example adds a new history value to the end of the history list. The value is the current time.

Copy

UpdateHistoryValueEx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Sub VhsUpdateHistoryValueEx()
    Dim VhsClient, req, resp, history, value, tag
    Set VhsClient = CreateObject("CxVhsLib.VhsClient.1")
    Set req = CreateObject("CxVhsLib.UpdateHistoryValueExReq")
    Set resp = CreateObject("CxVhsLib.UpdateHistoryValueExResp")
    Set history = CreateObject("CxVhsLib.HistoryEntryEx")
    Set value = CreateObject("CxVhsLib.ValueEntryEx")
    Set tag = CreateObject("CxVhsLib.HistoryTagStringEx")
    VhsClient.Connect("CYGDEMO.VHS")
     
    tag.TagString = "CYGDEMO.UIS.00000068:CYG_METER_PDIFF"
    req.TagStringEx = tag
     
    history.TimeStamp = Now
    history.Value = Time
    req.ValueEntryNew = history
     
    VhsClient.UpdateHistoryValueEx req, resp
     
    If resp.ErrorType <> 0 Then
        edtMessageBox.Text = "Error number " & resp.ErrorType
    Else
        edtMessageBox.Text = "Completed Successfully"
    End If
End Sub